3D Graphics Programming with QuickDraw 3D 1.5.4

Configuration Methods

This section describes renderer configuration methods, all of which are optional.

Q3XMethodTypeRendererIsInteractive

The Q3XMethodTypeRendererIsInteractive renderer support functionality is optional. If it is supplied, it should report whether or not the renderer is interactive.



 
#define kQ3XMethodTypeRendererIsInteractive Q3_METHOD_TYPE('i','s','i','n')

DESCRIPTION

There is no actual method required for kQ3XMethodTypeRendererIsInteractive. The metahandler just returns (TQ3XFunctionPointer)kQ3True if the renderer is intended to be used in interactive settings and (TQ3XFunctionPointer)kQ3False otherwise.

If neither value is returned, the renderer is assumed to be noninteractive.

TQ3XRendererModalConfigureMethod

The TQ3XRendererModalConfigureMethod renderer support functionality is optional. If it is supplied, it should display a modal dialog to let the user edit the renderer settings found in the renderer's private data.



 
#define kQ3XMethodTypeRendererModalConfigure 

                     Q3_METHOD_TYPE('r','d','m','c')



 
typedef TQ3Status (*TQ3XRendererModalConfigureMethod)(

                     TQ3RendererObject    renderer,

                     TQ3DialogAnchor      dialogAnchor,

                     TQ3Boolean           *canceled,

                     void                 *rendererPrivate);

renderer: A renderer object.
dialogAnchor: Platform-specific data passed by the client to support movable modal dialogs (described below).
canceled: Returns a boolean value to indicate that the user canceled the dialog.
rendererPrivate: A pointer to structure of size instanceSize , passed into Q3ObjectHierarchy_RegisterClass , and initialized in your kQ3MethodTypeObjectNew method.

DESCRIPTION

The renderer calls TQ3XRendererModalConfigureMethod for events not handled by the normal settings dialog; this is needed to support movable modal dialogs.

The dialogAnchor parameter is platform-specific. With the MacOS it is a callback to the calling application's event handler, which must return kQ3True if it handles the event passed to the callback and kQ3False if not. An application that doesn't want to support a movable modal configure dialog should pass NULL for the clientEventHandler field of TQ3DialogAnchor and should implement a nonmovable dialog.

Modal dialogs in windows applications are always movable. With Windows, therefore, dialogAnchor is the handle of the owning window, typically the application's main window.

TQ3XRendererGetNickNameStringMethod

The TQ3XRendererGetNickNameStringMethod renderer support functionality is optional. If it is supplied, it lets an application collect the name of the renderer for display in user interface items such as menus. Such a name may be localized or may be more user-friendly than the name string provided at registration.



 
#define kQ3XMethodTypeRendererGetNickNameString 

                     Q3_METHOD_TYPE ('r','d','y','u')



 
typedef TQ3Status (TQ3XRendererGetNickNameStringMethod)(

                     unsigned char    *dataBuffer,

                     unsigned long    bufferSize,

                     unsigned long    *actualDataSize);

dataBuffer: Data buffer to hold the renderer's name.
bufferSize: The actual size of the memory block pointed to by dataBuffer .
actualDataSize: On return, the actual number of bytes written to the buffer; or if dataBuffer is NULL , the required size of dataBuffer .

DESCRIPTION

An application uses TQ3XRendererGetNickNameStringMethod to get a user-identifiable name of a renderer. If dataBuffer is NULL , actualDataSize returns the required size in bytes of a data buffer large enough to store the renderer's name.

EXAMPLE

The following is example code for getting the name strings for all the currently-registered plug-in renderers.



 
void Menu_Init(

    void)

{

    Handle              menuBar;

    MenuHandle          menu;

    TQ3SubClassData     subClassData;

    TQ3ObjectType       *classPointer;

    short               i;



 
    if (!(menuBar = GetNewMBar(kMenuBar))) {

        SysBeep(1);

        ExitToShell();

    }



 
    SetMenuBar(menuBar);

    DisposeHandle(menuBar);

    DrawMenuBar();



 
    AddResMenu(GetMHandle(kMenu_Apple), 'DRVR');

    InsertMenu(GetMenu(...));



 
    menu = GetMHandle(kMenu_Renderer);



 
    Q3ObjectHierarchy_GetSubClassData(

        kQ3SharedTypeRenderer, &subClassData);



 
    classPointer = subClassData.classTypes;

    i = subClassData.numClasses;



 
    while (i--) {

        TQ3ObjectClassNameString            objectClassName;

        Q3RendererClass_GetNickNameString(

            *classPointer, objectClassName);

        AppendMenu(menu, c2pstr(objectClassName));

        gRendererCount++;

        classPointer++;

    }



 
    Q3ObjectHierarchy_EmptySubClassData(

    &subClassData);

}

TQ3XRendererGetConfigurationDataMethod

The TQ3XRendererGetConfigurationDataMethod renderer support functionality is optional. If it is supplied, it lets an application collect private configuration data from the renderer, which it will then save. The application may save the data in a preference file, in a registry key (in the Windows environment), or in a style template. The application will normally tag the data with the renderer's object name.



 
#define kQ3XMethodTypeRendererGetConfigurationData

                     Q3_METHOD_TYPE('r','d','g','p')



 
typedef TQ3Status (*TQ3XRendererGetConfigurationDataMethod)(

                     TQ3RendererObject    renderer,

                     unsigned char        *dataBuffer,

                     unsigned long        bufferSize,

                     unsigned long        *actualDataSize,

                     void                 *rendererPrivate);

renderer: A renderer object.
dataBuffer: Buffer to hold the renderer's configuration data.
bufferSize: The actual size of the memory block pointed to by dataBuffer .
actualDataSize: On return, the actual number of bytes written to the buffer; if dataBuffer is NULL , it is the required size of the buffer.
rendererPrivate: A pointer to structure of size instanceSize , passed into Q3ObjectHierarchy_RegisterClass , and initialized in your kQ3MethodTypeObjectNew method.

DESCRIPTION

The renderer calls TQ3XRendererGetConfigurationDataMethod to access configuration data from a renderer's private data space. If dataBuffer is NULL , actualDataSize returns the required size in bytes of a data buffer large enough to store the private data.

TQ3XRendererSetConfigurationDataMethod

The TQ3XRendererSetConfigurationDataMethod renderer support functionality is optional. If it is supplied, it lets an application pass private configuration data that it previously obtained via Q3Renderer_GetConfigurationData .



 
#define kQ3XMethodTypeRendererSetConfigurationData

                     Q3_METHOD_TYPE('r','d','s','p')



 
typedef TQ3Status (*TQ3XRendererSetConfigurationDataMethod)(

                     TQ3RendererObject    renderer,

                     unsigned char        *dataBuffer,

                     unsigned long        bufferSize,

                     void                 *rendererPrivate);

renderer: A renderer object.
dataBuffer: Buffer to hold the renderer's configuration data.
bufferSize: The actual size of the memory block pointed to by dataBuffer .
rendererPrivate: A pointer to structure of size instanceSize , passed into Q3ObjectHierarchy_RegisterClass , and initialized in your kQ3MethodTypeObjectNew method.

DESCRIPTION

The renderer calls TQ3XRendererSetConfigurationDataMethod to place previously obtained renderer configuration data into a renderer's private data space.